package com.mtoolkit.property;

import java.io.File;
import java.io.IOException;
import java.math.BigDecimal;
import java.math.BigInteger;
import java.net.URL;
import java.util.List;
import java.util.Map.Entry;
import java.util.Set;

/**
 * 读取属性文件相关操作的统一接口。
 * @version 1.00 2010-10-8, 18:00:42
 * @since JDK 1.5
 * @author ZhangShixi
 */
public interface IProperties {

    /**
     * 通过给定的属性文件的URL来载入属性文件配置信息。
     * @param url 属性文件对应的URL信息。
     * @throws java.io.IOException 加载属性文件异常。
     */
    public void load(URL url) throws IOException;

    /**
     * 通过给定的属性文件来载入属性文件的配置信息。
     * @param file 属性文件对应File实例。
     * @throws java.io.IOException 加载属性文件异常。
     */
    public void load(File file) throws IOException;

    /**
     * 通过给定的属性文件的路径来载入属性文件的配置信息。
     * @param classPath 属性文件所在的类路径。
     * @throws java.io.IOException 加载属性文件异常。
     */
    public void load(String classPath) throws IOException;

    /**
     * 获取指定键对应的属性值。
     * @param key 键值对的键。
     * @return 键值对的键所对应的值。
     * @throws java.util.NoSuchElementException 如果指定的键不存在，将抛出此异常。
     */
    public String getValue(String key);

    /**
     * 获取指定键的属性值。如果此属性值不存在，将使用调用者指定的默认值。
     * @param key 键值对的键。
     * @param defaultValue 当指定键对应的属性值不存在时的默认属性值。
     * @return 指定键的属性值。如果此属性值不存在，将使用调用者指定的默认值。
     */
    public String getValue(String key, String defaultValue);

    /**
     * 获取指定值对应的所有键的列表。
     * @param value 指定的属性值。
     * @return 属性值对应的键列表。
     */
    public List<String> getKey(String value);

    /**
     * 获取属性文件中所有键的Set视图。
     * @return 键的Set视图。
     */
    public Set<String> keySet();

    /**
     * 获取属性文件中配置的所有的值列表。
     * @return 所有的值列表。
     */
    public List<String> valueList();

    /**
     * 获取属性文件中所有键值对的Set视图。
     * @return 所有键值对的Set视图。
     */
    public Set<Entry<String, String>> entrySet();

    /**
     * 判断此属性文件配置中是否包含指定的键。
     * @param key 指定的键。
     * @return 是否包含指定的键。
     *      <code>true</code>包含，<code>false</code>不包含。
     */
    public boolean containsKey(String key);

    /**
     * 判断此属性文件配置中是否包含指定的值。
     * @param value 指定的值。
     * @return 是否包含指定的值。
     *      <code>true</code>包含，<code>false</code>不包含。
     */
    public boolean containsValue(String value);

    /**
     * 返回此属性文件中键值对的数量。
     * @return 属性文件中键值对的数量。
     */
    public int size();

    /**
     * 返回此属性文件是否已被载入。
     * @return 是否已载入。
     *      <code>true</code>表示已载入，<code>false</code>表示未被载入。
     */
    public boolean isLoad();

    /**
     * 返回此属性文件是否为空。
     * @return 属性文件是否为空。
     *      <code>true</code>表示为空，<code>false</code>表示不为空。
     */
    public boolean isEmpty();

    /**
     * 获取指定属性键对应的int基本类型的属性值。
     * @param key 属性键。
     * @return 属性键对应的int类型的属性值。
     * @throws java.util.NoSuchElementException 如果指定的键不存在，将抛出此异常。
     */
    public int getIntValue(String key);

    /**
     * 获取指定属性键对应的int类型的属性值。如果此属性值不存在，将返回指定的默认值。
     * @param key 属性键。
     * @param defaultValue 当指定键对应的属性值不存在时的默认属性值。
     * @return 属性键对应的int类型的属性值。如果此属性值不存在，将返回指定的默认值。
     */
    public int getIntValue(String key, int defaultValue);

    /**
     * 获取指定属性键对应的Integer类型的属性值。如果此属性值不存在，将返回指定的默认值。
     * @param key 属性键。
     * @param defaultValue 当指定键对应的属性值不存在时的默认属性值。
     * @return 属性键对应的Integer类型的属性值。如果此属性值不存在，将返回指定的默认值。
     */
    public Integer getIntegerValue(String key, Integer defaultValue);

    /**
     * 获取指定属性键对应的long基本类型的属性值。
     * @param key 属性键。
     * @return 属性键对应的long类型的属性值。
     * @throws java.util.NoSuchElementException 如果指定的键不存在，将抛出此异常。
     */
    public long getLongValue(String key);

    /**
     * 获取指定属性键对应的long类型的属性值。如果此属性值不存在，将返回指定的默认值。
     * @param key 属性键。
     * @param defaultValue 当指定键对应的属性值不存在时的默认属性值。
     * @return 属性键对应的long类型的属性值。如果此属性值不存在，将返回指定的默认值。
     */
    public long getLongValue(String key, long defaultValue);

    /**
     * 获取指定属性键对应的Long类型的属性值。如果此属性值不存在，将返回指定的默认值。
     * @param key 属性键。
     * @param defaultValue 当指定键对应的属性值不存在时的默认属性值。
     * @return 属性键对应的Long类型的属性值。如果此属性值不存在，将返回指定的默认值。
     */
    public Long getLongValue(String key, Long defaultValue);

    /**
     * 获取指定属性键对应的byte基本类型的属性值。
     * @param key 属性键。
     * @return 属性键对应的byte类型的属性值。
     * @throws java.util.NoSuchElementException 如果指定的键不存在，将抛出此异常。
     */
    public byte getByteValue(String key);

    /**
     * 获取指定属性键对应的byte类型的属性值。如果此属性值不存在，将返回指定的默认值。
     * @param key 属性键。
     * @param defaultValue 当指定键对应的属性值不存在时的默认属性值。
     * @return 属性键对应的byte类型的属性值。如果此属性值不存在，将返回指定的默认值。
     */
    public byte getByteValue(String key, byte defaultValue);

    /**
     * 获取指定属性键对应的Byte类型的属性值。如果此属性值不存在，将返回指定的默认值。
     * @param key 属性键。
     * @param defaultValue 当指定键对应的属性值不存在时的默认属性值。
     * @return 属性键对应的Byte类型的属性值。如果此属性值不存在，将返回指定的默认值。
     */
    public Byte getByteValue(String key, Byte defaultValue);

    /**
     * 获取指定属性键对应的double基本类型的属性值。
     * @param key 属性键。
     * @return 属性键对应的double类型的属性值。
     * @throws java.util.NoSuchElementException 如果指定的键不存在，将抛出此异常。
     */
    public double getDoubleValue(String key);

    /**
     * 获取指定属性键对应的double类型的属性值。如果此属性值不存在，将返回指定的默认值。
     * @param key 属性键。
     * @param defaultValue 当指定键对应的属性值不存在时的默认属性值。
     * @return 属性键对应的double类型的属性值。如果此属性值不存在，将返回指定的默认值。
     */
    public double getDoubleValue(String key, double defaultValue);

    /**
     * 获取指定属性键对应的Double类型的属性值。如果此属性值不存在，将返回指定的默认值。
     * @param key 属性键。
     * @param defaultValue 当指定键对应的属性值不存在时的默认属性值。
     * @return 属性键对应的Double类型的属性值。如果此属性值不存在，将返回指定的默认值。
     */
    public Double getDoubleValue(String key, Double defaultValue);

    /**
     * 获取指定属性键对应的short基本类型的属性值。
     * @param key 属性键。
     * @return 属性键对应的short类型的属性值。
     * @throws java.util.NoSuchElementException 如果指定的键不存在，将抛出此异常。
     */
    public short getShortValue(String key);

    /**
     * 获取指定属性键对应的short类型的属性值。如果此属性值不存在，将返回指定的默认值。
     * @param key 属性键。
     * @param defaultValue 当指定键对应的属性值不存在时的默认属性值。
     * @return 属性键对应的short类型的属性值。如果此属性值不存在，将返回指定的默认值。
     */
    public short getShortValue(String key, short defaultValue);

    /**
     * 获取指定属性键对应的Short类型的属性值。如果此属性值不存在，将返回指定的默认值。
     * @param key 属性键。
     * @param defaultValue 当指定键对应的属性值不存在时的默认属性值。
     * @return 属性键对应的Short类型的属性值。如果此属性值不存在，将返回指定的默认值。
     */
    public Short getShortValue(String key, Short defaultValue);

    /**
     * 获取指定属性键对应的boolean基本类型的属性值。
     * @param key 属性键。
     * @return 属性键对应的boolean类型的属性值。
     * @throws java.util.NoSuchElementException 如果指定的键不存在，将抛出此异常。
     */
    public boolean getBooleanValue(String key);

    /**
     * 获取指定属性键对应的boolean类型的属性值。如果此属性值不存在，将返回指定的默认值。
     * @param key 属性键。
     * @param defaultValue 当指定键对应的属性值不存在时的默认属性值。
     * @return 属性键对应的boolean类型的属性值。如果此属性值不存在，将返回指定的默认值。
     */
    public boolean getBooleanValue(String key, boolean defaultValue);

    /**
     * 获取指定属性键对应的Boolean类型的属性值。如果此属性值不存在，将返回指定的默认值。
     * @param key 属性键。
     * @param defaultValue 当指定键对应的属性值不存在时的默认属性值。
     * @return 属性键对应的Boolean类型的属性值。如果此属性值不存在，将返回指定的默认值。
     */
    public Boolean getBooleanValue(String key, Boolean defaultValue);

    /**
     * 获取指定属性键对应的float基本类型的属性值。
     * @param key 属性键。
     * @return 属性键对应的float类型的属性值。
     * @throws java.util.NoSuchElementException 如果指定的键不存在，将抛出此异常。
     */
    public float getFloatValue(String key);

    /**
     * 获取指定属性键对应的float类型的属性值。如果此属性值不存在，将返回指定的默认值。
     * @param key 属性键。
     * @param defaultValue 当指定键对应的属性值不存在时的默认属性值。
     * @return 属性键对应的float类型的属性值。如果此属性值不存在，将返回指定的默认值。
     */
    public float getFloatValue(String key, float defaultValue);

    /**
     * 获取指定属性键对应的Float类型的属性值。如果此属性值不存在，将返回指定的默认值。
     * @param key 属性键。
     * @param defaultValue 当指定键对应的属性值不存在时的默认属性值。
     * @return 属性键对应的Float类型的属性值。如果此属性值不存在，将返回指定的默认值。
     */
    public Float getFloatValue(String key, Float defaultValue);

    /**
     * 获取指定属性键对应的BigInteger类型的属性值。
     * @param key 属性键。
     * @return 属性键对应的BigInteger类型的属性值。
     * @throws java.util.NoSuchElementException 如果指定的键不存在，将抛出此异常。
     */
    public BigInteger getBigIntegerValue(String key);

    /**
     * 获取指定属性键对应的BigInteger类型的属性值。如果此属性值不存在，将返回指定的默认值。
     * @param key 属性键。
     * @param defaultValue 当指定键对应的属性值不存在时的默认属性值。
     * @return 属性键对应的BigInteger类型的属性值。如果此属性值不存在，将返回指定的默认值。
     */
    public BigInteger getBigIntegerValue(String key, BigInteger defaultValue);

    /**
     * 获取指定属性键对应的BigDecimal类型的属性值。
     * @param key 属性键。
     * @return 属性键对应的BigDecimal类型的属性值。
     * @throws java.util.NoSuchElementException 如果指定的键不存在，将抛出此异常。
     */
    public BigDecimal getBigDecimalValue(String key);

    /**
     * 获取指定属性键对应的BigDecimal类型的属性值。如果此属性值不存在，将返回指定的默认值。
     * @param key 属性键。
     * @param defaultValue 当指定键对应的属性值不存在时的默认属性值。
     * @return 属性键对应的BigDecimal类型的属性值。如果此属性值不存在，将返回指定的默认值。
     */
    public BigDecimal getBigDecimalValue(String key, BigDecimal defaultValue);
}
